Contents

ADVANSYS

Formativ

GroupWise Customization Made Easy!

User's Guide

Guide to using Formativ Admin 1.6 and Formativ Developer 1.6 for Novell GroupWise

Advansys Formativ User's Guide

Information in this document is subject to change without notice. The example companies, products and people are purely fictitious. Without limiting the rights under copyright, no part of this document may be reproduced, stored or introduced into a retrieval system, or transmitted in any form without prior written approval of Advansys corporation.

Advansys may have patents, patent applications, trademarks, copyrights, or other intellectual property rights covering the subject matter in this document. Except as expressly provided in any written license agreement from Advansys, the furnishing of this document does not give you any license to these patents, trademarks, copyrights or other intellectual property.

Copyright © 2003 Advansys Pty Limited. All rights reserved.

Formativ is a trademark of Advansys Pty Limited in Australia and other countries.

GroupWise is a registered trademark of Novell Inc.

Visual Basic Script is a trademark of Microsoft Corporation.


Welcome to Formativ

Welcome to Formativ - Unlimited Solutions for Novell GroupWise!

Welcome to Advansys Formativ. Advansys Formativ provides a new, exciting way for end-users, developers and power users to build dynamic solutions for Novell GroupWise, Novell's premier collaboration product.

Formativ represents the Advansys vision of providing powerful and easy to use GroupWise solutions for the wider GroupWise community. Because the Formativ applet language is based on industry standards, users are able to access rich functionality when building GroupWise solutions. By building solutions directly on top of Novell GroupWise using a unified, simple development tool and language, organizations are able to enjoy shorter development cycles and more satisfied users.

Formativ 1.6 includes:

  • Comprehensive, easy to learn applet language based on Visual Basic Script
  • Formativ Runtime, a runtime version that only allows the execution of Encoded applets (applets cannot be created or edited)
  • Over 500 applet commands to make accessing GroupWise information simple
  • The ability to record, playback and edit GroupWise applets
  • The ability to modify the appearance and functionality of the GroupWise client using applets
  • The ability to manage Formativ centrally using Novell eDirectory/NDS
  • Complete access to the GroupWise Object API and Administrative Objects API via applets
  • Comprehensive support for Custom Third Party Objects support via applets
  • The ability to create GroupWise 6.5 Trusted Applications
  • The ability to define new GroupWise custom message types, including opened and closed message icons.
  • Many real world sample applets designed to help you learn the basics of Formativ development
  • An integrated development environment (IDE)

Empowering the GroupWise Community

As more organizations adopt Novell GroupWise as their collaboration product of choice, developers are receiving an ever increasing number of requests to automate, extend and integrate GroupWise. The increase in demand places more pressure on development teams worldwide. The traditional development approach for GroupWise has forced many requests to go unsatisfied. Advansys Formativ simplifies GroupWise development by unifying the key GroupWise programming interfaces into a single, simple, yet extremely powerful applet development environment. By making GroupWise development easier, because of its simple approach and widely understood development language, Advansys Formativ empowers the wider GroupWise community in a manner previously unseen in the industry.

Build GroupWise Solutions Faster

Solutions built with Advansys Formativ are developed and deployed faster than those developed using conventional GroupWise programming techniques. Developers can now use the power and simplicity of applets based on Visual Basic Script to access GroupWise, instead of difficult to use third and fourth generation languages. With Formativ, developers do not need to master three or four different GroupWise programming interfaces to implement a solution as is often the case with traditional GroupWise development techniques.

Formativ ships with a number of pre-written applets which solve common GroupWise enhancement requests, such as multiple signatures, template support, search and replace within messages, holiday importing and data input/output. These pre-written applets help developers learn the basics of developing solutions with Formativ and also represent immediately useful functionality out of the box.

Formativ allows you to record GroupWise applets! You can simply start recording, and Formativ will record the sequence of actions you carry out in GroupWise. When you stop recording, an applet is automatically built for you that you can play back as-is, or further edit and enhance as a basis for a more complex applet. Recording applets makes automating simple tasks in GroupWise extremely simple.

Simplify Solution Deployment and Management

Developers who support large organizations often find it difficult to deploy and maintain GroupWise solutions. Formativ's centralized management capabilities makes it a trivial exercise to quickly deploy solutions using Novell eDirectory/Directory Services (NDS).

Rich Exposure of the GroupWise Architecture

Formativ introduces more than 500 applet commands to make accessing the GroupWise message store and architecture easy. In addition, Formativ provides complete access to the native GroupWise Object API and Administrative Objects API. The GroupWise Custom Third Party Objects API (C3PO) API is also covered, making integrating with the GroupWise client via user interface elements such as toolbar buttons/menu items, and trapping events, such as the 'OnSend' event, extremely simple.


What's New in Formativ 1.0

What's New in Formativ 1.6

Advansys Formativ is a completely new paradigm in GroupWise development. Developers and power users alike are now able to develop solutions based on Novell GroupWise 6 and 5.5 using powerful applets. You no longer need to be familiar with several application programming interfaces and development languages. Using Formativ, customizing and extending GroupWise has never been easier.

Formativ 1.6 now includes:

  • Formativ Portal Manager(tm)
  • GroupWise 6.5 support
  • Trusted Application Support
  • Custom Message Support, including icons
  • Improved Integrations Manager
  • Embedded and floating HTML dialogs
  • New Formativ Developer version
  • Flexalock(tm) applet support
  • New Info Tab in FormativCentral
  • Updated Formativ Control Panel applet
  • Business Solutions Pack now a separate product
  • Formativ Admin and Developer include runtime support
  • Updated configuration information in Formativ About dialog
  • Formativ Client is now renamed to Formativ Runtime
  • Multi-session login API support
  • New Save As feature in FormativCentral
  • Updated look and feel
  • New Formativ Registration Utility
  • Event override capability
  • Event ordering capability
  • Updated eDirectory/NDS support
    • Applet Compression
    • Intelligent Applet Caching
    • Local Applet Mode
    • LDAP Support
    • Protocol Switching
    • New Schema Wizard


Formativ Runtime

Advansys Formativ - Unlimited Solutions for GroupWise is available in a number of versions - Formativ Admin, Formativ Developer and Formativ Runtime. Formativ Runtime is the low cost extensible client and is for individual or enterprise users who require only the ability to execute pre-written applets. Formativ Developer provides the full range of applet creation, editing and execution, and is for individual or enterprise users who wish to develop Formativ applets but who do not need any eDirectory/NDS management features. Formativ Admin is the complete enterprise client, which provides the full range of applet creation, editing, execution and Novell eDirectory distribution and management functionality, and is for enterprise users who need to write and maintain applets and who also need to manage Formativ applet libraries using Novell eDirectory/NDS. Both Formativ Admin and Formativ Developer include full Formativ Runtime functionality.

The key features** of all Formativ versions are shown below:

Formativ Runtime

Low cost, extensible runtime environment

Stand-alone and enterprise modes of operation

Executes only Encoded and Flexalock applets

Includes Formativ Portal Manager for GroupWise

Includes Today View and No Junk Mail solutions

HTML forms support

Wide range of Formativ powered GroupWise solutions available

Supports access to Formativ eDirectory/NDS applet libraries

Supports eDirectory/NDS access via the NetWare client and LDAP

Seamlessly integrates with the GroupWise 32-bit client

Formativ Developer

Fully integrated applet development solution

Includes Formativ Runtime features

Create, edit and record applets

Protect your source code by distributing secure Encoded or Flexalock applets

Execute Encoded, Flexalock or open source applets

Ships with a wide range of open source applet examples

Formativ Admin

Fully integrated applet development and enterprise management solution

Includes both Formativ Runtime and Formativ Developer features

Central management of Formativ Developer and Formativ Runtime via eDirectory/NDS

Applet management and distribution via eDirectory/NDS

**Note: Features supported may vary according to the GroupWise 32-bit client version installed.

The majority of this documentation refers to Formativ Admin and Formativ Developer - not Formativ Runtime. See the Formativ Runtime documentation for more information.


Finding Information

This section provides information about using Formativ documentation, installing and configuring the product and obtaining support from Advansys.

For information about | See
Installing Formativ | This guide
Configuring Formativ | This guide
Using the Formativ Development Environment | This guide
The Formativ Language Guide | The Formativ Language Guide
The Formativ Business Solutions Pack Guide | The Formativ Business Solutions Pack Guide
Developing Solutions with Formativ | The Formativ Programmers Guide
Visual Basic Script | Microsoft's Visual Basic Script web site
Novell GroupWise Development Resources | Novell DeveloperNet web site
All other aspects of Formativ development |


Installation and Setup

System Requirements

Microsoft Windows 98, ME, 2000 or XP.

Novell GroupWise 5.5, 5.5 EP, 6.01+, 6.5 (or above) client.

Formativ Portal Manager for GroupWise and applets which use it, such as the Today View, requires GroupWise 6.01 or above. (Novell have released a beta FTF file for the GroupWise 5.5.7.1 Enhancement Pack client which enables the use of the Formativ Portal Manager™ based solutions with the GroupWise 5.5 EP client. See Novell TID 2963458 for details on the update and information on how to download the GroupWise 5.5.7.2 Beta FTF file (f32eppp1.exe).)

Microsoft Windows Script (5.5 or above recommended; normally installed by MS Internet Explorer).

Microsoft Internet Explorer 5.5 or above.

Installation Order

To ensure that Formativ works properly, please install the required components in the following order

1 - Novell GroupWise client

2 - Microsoft Internet Explorer

3 - Advansys Formativ Admin or Formativ Developer

Microsoft Windows Script Host

Advansys Formativ requires that you have the Microsoft Windows Script Host installed on your PC. Windows scripting was probably installed to your PC when IE was installed. However, if you encounter problems, it is available for download from Microsoft at:

http://www.microsoft.com/msdownload/vbscript/scripting.asp

IMPORTANT: Although Formativ requires the presence of the Windows Scripting Host, it does not use the host to run applets.

Installation

To install Formativ Runtime, first SHUT DOWN THE GROUPWISE CLIENT IF IT IS RUNNING, then run the supplied installation program.

Advansys Formativ can be removed from your computer via the Windows ‘Add/Remove Programs’ Control Panel applet. It can be disabled and enabled from the ‘Advansys Formativ' Windows Control Panel applet.

Notes

Even though Formativ does not use the .VBS extension for the applets it uses, you may wish to disable the association between .VBS and the Windows Script Host to stop potentially malicious Visual Basic Script code being run from email attachments. Use the security tab on the ‘Advansys Formativ' Windows Control Panel applet to disable the association. Having Formativ installed on your PC does NOT increase the likelihood of falling victim to Visual Basic Script viruses that plague Microsoft Outlook users. More information can be found in the Advansys Formativ Security white paper available from the Advansys web site http://www.advansyscorp.com

Once Formativ is installed, you should restart GroupWise. You may see a message stating that new events have been subscribed to and that a client restart is necessary. If this occurs, once GroupWise has started, close it down and restart it once more. You will see a new Applets menu option on the main GroupWise menu, and a new toolbar button. You will also see various other toolbar buttons and context menu items which represent the integrated sample applets.

Formativ Runtime will execute only Encoded or Flexalock applets created by Formativ Admin or by Formativ Developer, or applets which are stored in Formativ eDirectory/NDS applet libraries. See the Administrators Guide for information on setting up eDirectory/NDS applet libraries, and this guide for information on Encoded and creating Flexalock applets.


Getting Help from Advansys Technical Support

If you are currently online, select one of the following links to access the appropriate support resource:

Formativ Updates Page

There may be an update that addresses your problem. This page should be your first stop should you encounter a problem.

Formativ Support Page

The Formativ Support page contains links to various support resources.

Advansys Formativ Frequently Asked Questions (FAQ)

Advansys maintains a list of frequently asked questions about Formativ. Check this page to see if the answer to your question has already been documented.

Formativ Support Forums

Advansys provides technical support for Formativ via online moderated forums. These web-based forums are moderated by Advansys technical staff and represent the primary source of support for Formativ. Feel free to log in and post a question or search the existing forums to see if your question has already been answered.

If you have a question about Visual Basic Script...

Advansys cannot answer general questions regarding the use and syntax of standard Visual Basic Script. If you have a general VBS question, please refer to one of the many excellent VBS resources available. Some online resources include:

Microsoft's Windows Scripting Technologies web page

Microsoft's Visual Basic Script Usenet support forum

Microsoft's Visual Basic Script Training Courses

There are also many independent online resources available. Search for 'Visual Basic Script' or 'Windows Scripting' using your favorite search engine.


Business Solutions Pack Macros

Business Solutions Pack Applets

The Formativ Business Solutions Pack (BSP) is a set of professional, pre-written commercial applets supplied as 30-day trial solutions with Formativ Admin, Developer and Runtime. The BSP is available for purchase as a separate product. These applets provide additional functionality for GroupWise, addressing a number of common GroupWise enhancement requests straight out of the box. If you choose to install this option, by default the Business Solutions Pack installation program will install the applets into the My Applets library (Formativ's Local folder).

Note that the applets in the Business Solutions Pack already contain suggested GroupWise integrations (that is, definitions for adding buttons to GroupWise toolbars, items to menus and associations with GroupWise events). However, some applets may have their integrations disabled. To activate the integrations:

Display FormativCentral

Select the appropriate BSP applet in the applet list

Select the Integrations tab

Uncheck the Disable these integrations in GroupWise check box

Restart GroupWise

Note: You may not have access to the Business Solutions Pack applets if your administrator decides not to make them available.


Example Macros

Example Applets

A large number of example applets are available in the Example Applets Pack. These applets demonstrate various programming techniques you can use with Formativ. Some are complete solutions, while others are simple examples of particular techniques.

Note that the example applets may already contain suggested GroupWise integrations (that is, definitions for adding buttons to GroupWise toolbars, items to menus and associations with GroupWise events). However, most example applets may have their integrations disabled. To activate the integrations:

Display FormativCentral

Select the appropriate applet in the applet list

Select the Integrations tab

Uncheck the Disable these integrations in GroupWise check box

Restart GroupWise


Your First Macro

Your First Applet

Writing applets in Formativ is very simple. Follow the steps below to create a simple applet and add a new button to the main GroupWise toolbar that runs the applet.

To create a new Formativ Applet:

If it is not already running, start your GroupWise client.

Select Applets | Manage Applets from the main GroupWise menu, or click the FormativCentral toolbar button. FormativCentral appears.

Select the library in which you wish to create the new applet. Unless you have administrator rights, this will be the My Applets node.

Select New from the Formativ toolbar. A new applet shell appears in the editor, and a new applet name appears in the list of applets.

You have created a new applet! It does not do anything useful yet, and has a generic name, so the first step is to rename it, then add some applet commands to make it display a message.

To rename an applet:

Click the applet name in the list once. After a moment the name becomes editable.

Enter a new name for your applet, then press enter

Now edit the applet to make it display a message when run.

To add code to an applet:

If it is not already active, click once on the Applet Editor tab to make it visible

Position the cursor on the blank line after the Sub Main(Client, Event) line, and enter the following text:

MsgBox("Hello World!")

Your applet should now look like:

'---------------------------
' Insert your comments here
'---------------------------

Sub Main(Client, GWEvent)
     MsgBox("Hello World")
End Sub

Run your applet by pressing the F5 key. A message box appears with the message "Hello World"

Integrating applets with the GroupWise client is very easy. Formativ lets you create buttons on toolbars, add items to menus and hook into GroupWise events to run your applets. The next step is to create a button on the main GroupWise toolbar that runs the applet. You will also specify some text for the button, a help hint for the button and select an image to appear on the button.

To specify properties for an applet:

Select the Properties tab

Enter a description and help hint for the applet (e.g. "My Applet").

Click once on any of the images shown to associate that image with the applet.

To create a button on the main GroupWise toolbar that runs your applet:

Select the Integrations tab

Double click the GroupWise main window entry in the tree shown. It expands to show another level

Double click the Toolbars entry. It expands to show another level

Click once in the entry labeled Main. This means you wish to add a button to the Main GroupWise toolbar

Close FormativCentral by clicking the Close menu item in the top left hand corner of the window

Restart the GroupWise client

When the client restarts, you will notice a new button on the main toolbar. It will have the same image you selected for your new applet. Move the mouse pointer over the button. You will see a help hint appear with the hint text you supplied. If you have GroupWise configured appropriately, you will also see the applet description text on the button. Run your applet by pressing the new button once. The "Hello World!" message appears!

This simple example illustrates many key points about Formativ development:

  • You manage applets from FormativCentral

  • To edit an applet, or change its properties, select it from the list of applets shown down the left side of the window, then select the appropriate tab from the right side

  • You do not have to save any changes you make while in FormativCentral explicitly - Formativ saves them for you. You can save the changes you make to applets as you edit them by pressing CTRL+S in the editor

  • Each applet has a description, help hint and an image

  • You integrate an applet with the GroupWise client by selecting the Integrations tab, then checking the appropriate box to create a button, menu item or event hook to run an applet.

  • In some cases you have to restart the GroupWise client before your integrations become active.


Recording Macros

Recording Applets

The Formativ applet recording facility gives you a head start with your applet writing by allowing you to record actions within GroupWise, and then convert those actions into applets. You can then run the newly recorded applets as-is, or you can edit and extend them as you please.

Starting Recording

To start recording, select Applets | Start Recording from the main GroupWise menu. At this point Formativ is recording GroupWise events. Perform the series of actions in GroupWise you wish to record, then stop the recording process as detailed below.

Stopping Recording

To stop recording, select Applets | Stop Recording from the main GroupWise menu. Formativ stops recording GroupWise events and automatically displays the applet editor. The applet editor contains a new applet based on the actions you recorded in GroupWise. You can now execute this applet, edit it, rename it, and integrate it with the GroupWise client as desired.

IMPORTANT

GroupWise does not allow Formativ to record every action you may perform. For this reason, a recorded applet may not play back exactly the same functions as recorded. In some cases, it may not play back at all. In these situations you will have to edit the applet manually to get it to perform the desired action. See the language guide for information on what commands you should use to achieve your goals.


The Formativ IDE

FormativCentral (IDE)

After Formativ Admin or Formativ Developer has been properly installed, you are free to create and execute applets. Start the GroupWise client. You will note a number of new buttons have been added to the main GroupWise toolbar. A new menu item called Applets has also been added. Select the Applets menu, then select the Manage applets option. This activates FormativCentral.

FormativCentral

FormativCentral is Formativ's Integrated Development Environment or IDE. This is where you create new applets, edit existing applets, set applet properties, such as descriptive names and help hint text, and integrate applets with the GroupWise client.

FormativCentral is modal. This means that it must be closed before you perform any other actions in GroupWise. While you can execute applets while FormativCentral is open, we recommend that you close it whenever it is not being used.

FormativCentral consist of two main areas: An applet list down the left side of the dialog, and the applet properties area down the right side. The applet properties area is divided into four tabs:

Tab name | Description
Editor | The applet editor allows you to edit an applet. Click here for more information about the applet editor.
Integrations | Lets you specify the buttons, toolbars, menus and events that will activate the current applet. Click here for information about applet integrations.
Properties | Lets you select an image that appears on any GroupWise toolbar button integrations, along with a description and help hint, which will also appear in the GroupWise client. You can also configure an applet to appear on Formativ's 'Applets' menu from here and disable an applet’s integration with GroupWise. Click here for information about applet properties.
Info | The Info tab enables you to specify the Author/Vendor information, applet version and comments. It also displays the expiry date of a Flexalock applet which includes one. Click here for more information about applet information.

Now you are familiar with the general layout of FormativCentral, click here to start creating applets!


The Macro Listing

The Applet Listing

The applet listing appears down the left hand side of FormativCentral. It shows all the applets you have created yourself, plus any other applets that your administrator might have made available to you.

My Applets

The My Applets node of the applet list contains all of your personal applets. When you create a new applet, it appears under this node.

A typical list entry appears as shown below:

The image at the start of the entry represents the image that will be used if you define a toolbar button in GroupWise that executes this applet. The image can be changed by using the applet Properties tab.

The text in the entry represents the name of the applet.

The small jigsaw puzzle pieces [image] image at the end of the entry indicates that GroupWise client integrations, such as toolbar buttons, menus and event hooks have been defined for this applet. Select the Integrations tab to edit these integrations. If no integrations have been defined, this image does not appear. If the integrations have been disabled, the [image] icon appears instead of the [image] icon.

An Encoded applet will have the [image] symbol at the end of the applet name.

A Flexalock applet will have the [image] symbol at the end of the applet name.

To create a new applet:

Select the My Applets node, or an applet under the My Applets node

Press the New button on the FormativCentral toolbar, or press Ctrl+N

A new applet skeleton will be created. It will be called New Applet by default.

To rename an applet in the list:

Select the applet you wish to rename

Click and hold down the mouse button over the applet for approximately 1 second, then release the mouse button. A selection border will be drawn around the applet name

Enter a new name for the applet. You can only use letters of the alphabet, numbers and spaces in the name

Press enter to rename the applet

To delete an applet from the list

Select the applet you wish to delete

Press the Delete button on the FormativCentral toolbar, or press Ctrl+Del

Note: Deleted applets can be undeleted from the Windows Recycle bin.

To run an applet from the list:

Select the applet you wish to execute

Press the Run button on the FormativCentral toolbar, or press F5

Note: FormativCentral is minimized and moved to the top of the screen when an applet is running. It is automatically restored once applet execution is complete.

To make a copy of an applet:

Select the applet you wish to copy

Press Ctrl+C to copy the applet

Press Ctrl+V to paste the applet. The copy appears, renamed to Copy of <original name>

To save an applet to another folder:

Select the applet you wish to save

Right-mouse click to display the context menu

Select Save As, choose the folder and applet name

To add an applet to your Favorites list:

Select the applet you wish to add to the favorites list

Right mouse click to display the popup menu

Select Favorite Applet

Note: The applet will not appear on the Favorites menu until you restart GroupWise. You can remove an applet from the Favorites menu by performing the same steps above and unchecking the Favorite Applet menu option.

To sort the applet listing:

Select either a library node, or an applet within that library

Right-mouse click to display the context menu

Select one of the four sort options

Applet Libraries (Formativ Admin only)

Your administrator might assign you one or more shared applet libraries. These are collections of applets that you can execute, but not edit. These applets appear in the applet listing under a library node [image]. A library node [image] is indicated by the name of the library and its description in brackets. If you are a library administrator, please see the Formativ Administrators Guide for information on using Formativ Admin in this mode.


Macro Editor

Applet Editor

Overview

The FormativCentral applet editor is a fully featured code editor. You should use it as you would any other code editor. Note that you do not have to save the changes you make in the editor manually. Formativ will automatically save any changes when you close down FormativCentral or select another applet. You can however save your changes manually by pressing the Save button on the editor toolbar, or by pressing Ctrl+S.

Shortcut Keys

F5 | Run the current applet
Ctrl+C | Copy the current selection to the clipboard
Ctrl+X | Cut the current selection to the clipboard
Ctrl+V | Paste the contents of the clipboard to the editor
Ctrl+S | Save the current applet
Ctrl+A | Select all of the applet source
Ctrl+F | Display the search dialog
Ctrl+R | Display the replace dialog
Ctrl+P | Display the print setup/preview screen
Ctrl+B | Insert a bookmark at the current location
Ctrl+H | Move to the current bookmark

Editor Options

To change the properties of the editor, right-mouse click in the editor and select Editor Properties to display the Editor Options dialog. This dialog lets you configure general editor options, syntax highlighting, hot key assignment, auto-correct settings and code templates.


Macro Integrations

Applet Integrations

The applet Integrations tab lets you integrate an applet with the GroupWise client. An applet integration lets you create a toolbar button, menu item, context menu item or event hook that executes your applet. You can create any number of applet integrations for a single applet. For example, you can create a button, menu item and event hook that all execute the same applet.

Version 1.6 and above also lets you control the order in which an applet executes in relation to the original GroupWise event (i.e. before the event, after the event, or in place of the event). This facility provide an extremely granular control over GroupWise.

When you assign integrations to an applet, the information about that integration is saved with the applet file. This means that if you distribute the applet to other users, its integrations will also automatically appear within the GroupWise client. For example, if you write an applet that proxies to another user, and you decide to create a button on the main GroupWise toolbar that executes the applet, any user to which you distribute the applet will automatically have the same button appear on their toolbar the next time they start GroupWise.

At GroupWise startup, Formativ must register its interest with any GroupWise context with which it wishes to integrate. The underlying GroupWise architecture means that, in some cases, Formativ is unable to register interest in a particular context in time for it to take effect. For example, if you write an applet, and create a button for the script on the main toolbar, the button will not appear until you restart the client. Formativ will attempt to identify these situations and advise the user that a client restart is required. If any new integrations you design do not appear, or the events you subscribe to do not fire, restart the GroupWise client and retry.

Integration Properties

The Integration Properties area of the Integrations tab contains three check boxes:

Enable Integrations - Check this option to enable all integrations in the GroupWise client. Uncheck this option to disable all integrations in the GroupWise client. Disabled integrations do not appear on any toolbars or menus, and are not automatically executed in response to GroupWise events.

This Applet Appears on the Favorites Menu - Check this option to have the applet appear on the Formativ Favorites menu within the GroupWise client.

The Applet Appears on the Run Menu - Check this option to have the applet appear on the Formativ Run menu within the GroupWise client.

GroupWise Contexts

When you define an integration with the GroupWise client, the integration is active within a particular GroupWise Context. A GroupWise Context essentially maps to either a message type or to some aspect of the GroupWise client. For example, each message type (email, appointments, notes etc) has its own context. The context is represented by a descriptive name, such as 'GroupWise Email' or 'GroupWise Appointments'. Each context is divided into categories, such as 'Toolbars', 'Menus' and 'Events', and the category is further subdivided into options. For example, the 'Events' category of the 'GroupWise Email' context consists of all the events you can assign applets to, such as 'On Send' and 'On Open'.

Adding Buttons to Toolbars

Formativ lets you add any number of buttons to most toolbars in the GroupWise client. For each button you define, Formativ lets you supply the text that appears on the button, the hint text that appears when you hold the mouse pointer over the button, and an image for the button.

As with all integrations, defining a button is context based. This means you can assign a button to appear with one or more GroupWise contexts. To define where the button should appear, select the Integrations tab within FormativCentral and select the context you wish to define the button within. Finally, check the Toolbar option that correlates to the context. The next time you start the GroupWise client, a button will appear on the main toolbar with the image, caption and help hint you defined. Clicking the button will execute the applet.

You can define any number of buttons that execute a single applet. For example, if you would like to have the same button described above also appear on the email dialog toolbar, locate the 'Mail' context, then check the Toolbars check box. The GroupWise client will now have two new buttons that execute the same applet. One will appear on the main menu, another will appear on the email view dialog.

Adding Items to Context Menus

Formativ lets you add context menu (also known as right mouse click, floating or pop up menus) items in the GroupWise client. These menus appear when you press the right mouse button over a particular item in the GroupWise client. For example, if you select an email message in a folder and press the right mouse button, a context menu appears that contains options specific to email items.

As with all integrations, defining a context menu item is context based. To define which context menu an item should be added to, select the Integrations tab within FormativCentral and locate the context in which you wish to add the context menu item. For example, if you would like to add the item to the context menu that appears when you right mouse click over an email message, locate the 'Mail' context, then check the Pop up option that correlates to the context. The next time you right mouse click over an email message, the context menu that appears will contain a new item with the caption and help hint you defined for the applet. Selecting the context menu item will execute the applet.

The context GroupWise uses can change depending where the mouse is when you right click. Be aware of this when defining context menu integrations. You may have to define several context menu integrations to have your applet accessible from all the menus you require your new item to appear upon.

Adding Items to Menus

Formativ lets you add any number of menu items to most top level menus in the GroupWise client. For each menu item you define, Formativ lets you supply the text that appears on the menu and the hint text that appears when you hold the mouse pointer over the menu item in the client.

As with all integrations, menu integrations are context based. This means you can assign a menu item to appear within one or more GroupWise contexts. To define where the menu item should appear, select the Integrations tab within FormativCentral and locate the context for which you wish to define the menu item.

For example, if you would like to add the menu item to the GroupWise main menu under the File menu option, locate the 'GroupWise Main Window' context, then click the button under the 'Menus' column. On the pop up that appears, locate the 'File' menu item, then check the slot where you want the new menu item to appear. The next time you start the GroupWise client, a menu item will appear on the GroupWise 'File' menu that executes your applet when it is selected.

You may define any number of menu items that execute a single applet. For example, if you would also like to have the same menu item as described above appear on the email dialog toolbar, double click the 'Mail' context, then follow the same direction as shown above. The GroupWise client will now have two new menu items that execute the same applet. One will appear on the main menu, another will appear on the email view menu.

Associating Applets with Events

Formativ lets you execute an applet when particular GroupWise events occur, such as when the GroupWise client starts up, a new message appears in your mailbox, or when you send a new item.

There is a wide range of events you are able to associate applets with. Most of the events of interest are those associated with the GroupWise message contexts, such as 'Mail' and 'Appointments'. For example, Formativ lets you associate an applet with the 'On Send' event of all message types, giving you the capability to write applets that perform some action prior to a message being sent.

Events are given names starting with 'On', such as 'On Send', 'On Print' and 'On Open'.

As with all integrations, associating an applet with a GroupWise event is context based. To define which event an applet should be executed with, select the Integrations tab within FormativCentral and locate the context in which you wish to associate the event. For example, if you would like to run an applet when the user presses the 'Send' button after creating a new email message, select the 'Mail' context, then press the button under the 'Events' column. Locate the 'On Send' check box and select it. The next time the email send button is pressed, the applet will be executed.

You can associate a single applet with multiple events within the same context, or with multiple events within different contexts. For example, you might associate a single applet with the 'On Compose' and 'On Reply' events of all the message types.

Take care when associating applets with events. While it is technically possible to associate an applet with any supported events, try to limit the intrusiveness of your applets with events as much as possible. Also, some applets lend themselves to association with events more than others. For example, while it makes good sense to associate a signatures or disclaimer applet with the 'On Send' event, other applets may not lend themselves as favorably.

Formativ 1.6 introduces the concept of event ordering. Event ordering lets you specify when your applet is to be executed in relation to the original GroupWise event that triggered the event. You can also choose to execute your applet in place of the event, effectively changing the default behavior of the GroupWise client.

To change the order in which your applet is executed, relative to the GroupWise event that triggered your applet, display the event pop up for the appropriate context and check the appropriate events. Use the drop down control next to each event to specify that you want your applet to execute Before the GroupWise Event, After the GroupWise Event, or your applet should Replace the GroupWise Event.


Macro Properties

Applet Properties

Each applet has a number of properties you can set. If you don't set any properties, the default values are used. Applet properties are used to specify the text that appears on buttons and menu items should an applet be associated with these. Applet properties also include an image that appears on buttons. You can also specify whether an applet should appear on the Formativ Favorites menu in the GroupWise client.

Applet properties are accessed from the properties tab with FormativCentral.

Applet Description

The applet description is the text that describes an applet. If you specify that an applet should be run from a button within GroupWise, the applet description appears on the face of the button if GroupWise is configured appropriately. If you specify that the applet appears on a GroupWise menu, the applet description text appears as the menu item text.

It is recommended that you keep applet descriptions as short as possible. GroupWise widens all toolbar buttons to be the width of the longest button caption. If you have configured GroupWise to display the button captions, long descriptions can make the GroupWise client untidy.

Applet Help Hint

The applet help hint is text that appears over buttons when the mouse pointer is held over a button for a few moments. The applet help hint text is used to provide feedback to the user as to the purpose of a particular button. This is particularly useful when you are not displaying captions in GroupWise toolbars.

You should make applet help hints as descriptive as possible.

Applet Image

The applet image is the image that appears on GroupWise toolbar buttons should you create a button to run an applet. This image is also used to identify the applet in the FormativCentral script listing.

Currently you can only select from a pre-defined group of images. A future release will include the capability to design your own images.

Should you share an applet to a GroupWise client that does not have the appropriate image library installed, a default image will be used.


Applet Info

The Applet Info tab enables the input of key author/vendor information for the applet. You can use the Set as defaults and Use defaults buttons to set or include default information in the fields marked with the green tick icon. If a Flexalock applet is highlighted in the FormativCentral applet list, and if it contains an expiry date, the expiry date will be displayed.

The following fields can be edited for an applet:

Author/Vendor

Email Address

Web Site

Phone

Version

Comments

Minimum Formativ Version Required

Tick denotes fields which can be set with, and be used to set, the default information.

Set as defaults button

Use the Set as defaults button to set as the default any existing text within the Author/Vendor, Email Address, Web Site and Phone fields. When this button is pressed, any text in these fields are stored in the Windows Registry for later use by the Use defaults button.

Use defaults button

Pressing the Use defaults button will automatically populate the first four information fields (marked with the [image] above) with any previously saved default text (see Set as defaults button above).


Encoding Macros

Encoded Applets

Formativ Admin and Formativ Developer include features to secure open source applets as Encoded or Flexalock applets for use with Formativ Runtime, Developer or Admin. Encoded applets were originally introduced in Formativ 1.0 for exclusive use by the Runtime (Client) version. Encoding an applet secures and hides the inner workings of the original open source applet. With the introduction of Formativ 1.5, all versions of Formativ can execute Encoded applets.

The creation of Encoded and Flexalock applets is a one way process - Encoded and Flexalock applets cannot be decoded. Because of this, Encoded applets are automatically copied to a special directory during the encoding process. The default encoding directory is C:\Program Files\Advansys\Formativ\Encoded. (This directory can be changed using the Formativ Control Panel applet.)

The key features of an Encoded applet are:

an Encoded applet cannot be decoded;

the GroupWise client integrations defined within the applet cannot be changed;

no part of the applet source code can be changed;

Formativ Runtime, Formativ Developer and Formativ Admin can execute Encoded applets;

only Formativ Admin and Formativ Developer can encode applets; and

an Encoded applet cannot be published to a Formativ eDirectory/NDS library.

Flexalock applets were introduced in Formativ 1.5 for use with all versions of Formativ. Unlike Encoded applets, Flexalock applets can be published to Formativ eDirectory/NDS applet libraries. Flexalock applets can also include a fixed expiry date, which enables commercial developers to create evaluation versions for their customers. See Flexalock Applets for more information.

You encode applets using tools available in FormativCentral.

To encode an applet:

Display FormativCentral

Select the applet you wish to encode

Right mouse click to display the pop up menu

Select Encode

A warning message is displayed advising where the Encoded applet will be created, and any existing applet with the same name will be overwritten. If you wish to proceed, select Yes.

The applet is encoded and copied to the Encoded directory. Any existing Encoded applet with the same name is overwritten. You may now manually distribute the Encoded applet to the local directory of Formativ users.

Note: Unlike Formativ Admin and Formativ Developer, Formativ Runtime can execute only Encoded or Flexalock applets (Formativ Runtime cannot execute open source applets nor can it encode or create Flexalock applets). Formativ Runtime can execute applets when they are published to shared Formativ eDirectory/NDS libraries.


Commercializing Applets

Flexalock(tm) Applets

Formativ Admin and Formativ Developer include features to secure open source applets as Encoded or Flexalock(tm) applets for use with Formativ Runtime, Developer or Admin. Flexalock applets were introduced in Formativ 1.5 for use with all versions of Formativ. Unlike Encoded applets, Flexalock applets can be published to Formativ eDirectory/NDS applet libraries. In addition, users of Formativ Admin or Developer can, if desired, change how the Flexalock applet is integrated with the GroupWise client, including toolbar icons, menu location and descriptions and the events which may trigger the applet to run. Flexalock applets can include a fixed expiry date, which enables commercial developers to create evaluation versions for their customers. In addition, the developer can decide to display in a special dialog, upon each GroupWise client startup, the remaining period before the applet expires.

The creation of Encoded and Flexalock applets is a one way process - Encoded and Flexalock applets cannot be decoded. Because of this, Flexalock applets are automatically copied to a special directory during the Flexalock creation process. The default Flexalock directory is C:\Program Files\Advansys\Formativ\Flexalock. (This directory can be changed using the Formativ Control Panel applet.)

Quick Start

At the basic level, a Flexalock applet can be created by simply selecting it from the applet list in FormativCentral, performing a right-mouse click and selecting Flexalock and pressing OK on the Flexalock Properties dialog. This will fully secure the applet source and place a Flexalock version of the applet into the default Flexalock applet folder, which is usually c:\program files\advansys\formativ\flexalock\. To make it easy to distinguish the Flexalock applet name from the original applet name, the Flexalock process automatically appends the suffix '_Flexalock' to the original applet name, i.e. OriginalName_Flexalock.vbf.

The '-->Flexalock command

The '-->Flexalock command is a key option for customizing a Flexalock applet. If the '-->Flexalock command does not appear in the applet source code prior to creating the Flexalock applet, the full applet source code will be secured (encrypted). The resultant Flexalock applet will not be human readable nor can it be modified without destroying its ability to run.

Adding the '-->Flexalock command to a 'legal' location (see below) in the top section of the applet source prior to the Flexalock process, enables the applet developer to expose comments and constant commands (see below for more details). This provides the developer with additional flexibility for allowing end-users to fine tune an applet's configuration (exposed constant values) and to provide descriptive instructions in a comments area. For security reasons, apart from constant and comment commands, no other programming commands can be added to the source code area prior to the '-->Flexalock command. The '-->Flexalock command, which is essentially a custom comment recognized by Formativ, must be on a line by itself (i.e. it can be the only command or text present on the same line of code).

An example of the '-->Flexalock command being included in the original source code is shown below. By exposing the const MsgBoxDisplayed constant command, a Formativ customer may, if required, change it to TRUE or FALSE to meet their specific requirements. The applet shown is a very simple example and, as required, any number of constant and comment commands may be exposed prior to the '-->Flexalock command.

Note: If 'illegal' commands (i.e. not a constant or comment command) are found during the Flexalock creation process, a Flexalock applet cannot be created. In addition, if an attempt is made to add illegal commands to the unencoded area of a Flexalock applet, an error will occur when a user attempts to execute it.

'-----------------------------------------------------------------------------
' Formativ Solutions for GroupWise
' Example Applet
' Designed by: Formativ Business Solution Team
' Copyright (c) 2002 Advansys Corporation (www.advansyscorp.com)
' Version 1.0
'
' DESCRIPTION
' The applet description goes here. It can be as detailed as required.
'
' INTEGRATIONS: Main GroupWise toolbar and Applet|Run menu.
'-----------------------------------------------------------------------------

'===============================================================================
' Change the constant below to control whether the dialog should be displayed
const MsgBoxDisplayed = TRUE
'===============================================================================

'-->Flexalock
'Global variables
HRT = Chr(13) & Chr(10)
DEFAULTFOLDER = Utilities.GetDataDirectory

'-----------------------------------------------------------------------------
' Main line processing
'-----------------------------------------------------------------------------
Sub Main(Client, GWEvent)

if MsgBoxDisplayed then
call msgbox("Default folder: " + HRT + HRT + DEFAULTFOLDER, 64, "Display Default Folder")
end if

End Sub

If we create a Flexalock applet from the above open source applet, when the resultant Flexalock applet is viewed in Formativ Admin or Developer, it will look like the code shown below. Notice that, apart from any comments or constants prior to the '-->Flexalock command, any source code following the '-->Flexalock command is fully encrypted.

'-----------------------------------------------------------------------------
' Formativ Solutions for GroupWise
' Example Applet
' Designed by: Formativ Business Solution Team
' Copyright (c) 2002 Advansys Corporation (www.advansyscorp.com)
' Version 1.0
'
' DESCRIPTION
' The applet description goes here. It can be as detailed as required.
'
' INTEGRATIONS: Main GroupWise toolbar and Applet|Run menu.
'-----------------------------------------------------------------------------

'===============================================================================
' Change the constant below to control whether the dialog should be displayed
const MsgBoxDisplayed = TRUE
'===============================================================================

'-->Flexalock0000000000000140
UmcUFPZyBUylAHr29fAQf/R7lEL7P/qjIUBD+1D5IyvBmU3erUZTQe4or2PCttG02DXN7HC6F5BH
hAUdPCXAPotsm2kunk8DQP7msLJFb5utOaShOxD1LLZizA6ncPPnoA1c3FtvlnPDKZFHmbic0DiN
eah3gCdc+nF/qx9/sp6GxW2BdPw5YrSNKWf1s+1ALnBk6uDk4TN90FNhu3uvCFoWQxizBcTv/mSR
eZw3mrL9DImPwJpsHSzSbTWUcqJfZRaJUIG3dLg7g2dMSvgynWGa+J0AKL59I02iJ5D5JClADfcm
MOSYog==

Adding an applet expiry date

A Flexalock applet can include an expiry date. This is useful for developers who wish to provide a trial applet solution to a GroupWise customer, either for beta test or commercial evaluation.

Adding an expiry date is easy. On the Flexalock Properties dialog, just check the option 'Make this applet expire on the following date:' and select the desired expiry date from the date control.

A number of developer options are available when adding an expiry date to a Flexalock applet:

the expiry date;

the text message which will display when the applet expires;

the trial period remaining for the applet can be set to display on GroupWise startup in a special information dialog; and

the applet author information which appears on applet expiry or GroupWise startup.

The applet trial period information dialog

On GroupWise client startup, Formativ will first check if any of the Flexalock applet information should be displayed. If so, the 'Trial Flexalock applets detected' dialog will display, listing only the Flexalock applets which have been defined by the developer to display on GroupWise startup. When an applet in the list is highlighted, the author information fields will display the following data from the Applet Info tab:

Author/Vendor

Email Address

Web Site

Phone

The applet expired dialog

When a Flexalock applet reaches its expiry date, any attempt to run the applet will display the 'Applet has expired' dialog. The expiry dialog will indicate the date when the applet was configured to expire and it provides the following data from the Applet Info tab:

Author/Vendor

Email Address

Web Site

Phone

Altering a Flexalock applet's GroupWise client integrations

Unlike encoding, a Flexalock applet does not lock the capability to change the applet integrations or properties. By using Formativ Admin or Developer, applet integrations and properties can be modified within FormativCentral. While in most cases there will not be a need to alter the integrations or properties defined by the developer, the ability to do so provides maximum flexibility for optimizing the solution for different GroupWise environments.

In summary, to create a Flexalock applet:

Display FormativCentral

Select the applet you wish to 'Flexalock'

If required, add the '-->Flexalock command at the desired point in the applet source code

Right mouse click to display the pop up menu

Select Flexalock

If required, modify the name for the Flexalock applet

If required, select an expiry date for the applet

If required, modify the expiry message text, which will be displayed when the Flexalock applet expires

Select if you want the applet trial period information dialog to display upon GroupWise client startup

A warning message is displayed advising where the Flexalock applet will be created, and any existing applet with the same name will be overwritten. If you wish to proceed, select Yes.

The applet is secured and copied to the Flexalock directory. Any existing Flexalock applet with the same name is overwritten. You may now manually distribute the Flexalock applet to the local directory of Formativ users or provide it to a customer for publishing into an eDirectory Formativ applet library.

Note: Unlike Formativ Admin and Formativ Developer, Formativ Runtime can execute only Encoded or Flexalock applets (Formativ Runtime cannot execute open source applets nor can it encode or create Flexalock applets). Formativ Runtime can execute applets when they are published to shared Formativ eDirectory/NDS libraries.


Live Help

Help

The FormativCentral Help Button and Help Button drop down menu (click small arrow on right of button to see the menu) contains links to useful resources. Some of the links shown on the help drop down menu open local documents installed with Formativ (represented by the disk icon). Others are links to internet-based documents (represented by the document/world icon -> you must be connected to the internet to access these links).


Control Panel Applet

Formativ provides a number of options configurable by end users. These are accessed via the Formativ Control Panel Applet. The Control Panel Applet is a separate application which can be accessed via the Windows Control Panel.

To access the Formativ Control Panel Applet:

Click the Windows Start Menu

Click the Settings menu option

Click the Control Panel menu option. The Windows Control Panel window appears

Double click the Advansys Formativ icon to start the applet.

The Formativ Control Panel applet consists of a number of tabbed option pages. As a general rule these settings should be changed only by your system administrator.

General

Enable/Disable Features

Use the check box controls to enable or disable Formativ, the Applet Recorder, the Command Blocker and the GroupWise 'Tip of the Day' feature. If you change any of these options, you need to restart the GroupWise client before the changes will take effect. This facility can be useful if you need to run GroupWise without loading Formativ or the Command Blocker. (Note: Disabling Formativ using this technique does not completely stop Formativ interacting with GroupWise. To dissociate Formativ completely from GroupWise you need to use the Windows uninstaller to uninstall it.)

Additional Security

Enable/Disable VBS Associations

This check box enables/disables the Windows association between the Windows Script Host and files with VBS or VBE extensions every time GroupWise is started. Disabling the association helps ensure that you don't inadvertently run VBS or VBE scripts that may contain malicious code.

The Restore Association button restores the association between the Script Host and VBS/VBE files.

It is important to note that Formativ does not run VBS or VBE scripts, and installing Formativ does not make you vulnerable to attack by VBS viruses, such as those which affect Microsoft Outlook. Formativ uses a proprietary file format, and provides its own hosted environment in which applets are executed. More information regarding the security features of Formativ in regards to script viruses is available from the Formativ Web site.

Local Config

The local config tab contains a number of options which can tailor Formativ's operational characteristics. If your administrator has configured your Formativ installation to run with an eDirectory/NDS Formativ Configuration object, changing these settings will have no effect because your configuration object's enterprise settings will take priority over any local settings.

If you have the rights to run in local settings mode, you can enable/disable Formativ, enable/disable standard applet integrations, change how the applet local cache is handled (when using Formativ eDirectory libraries only), whether you can run applets from the Run and Favorites menus and change the name of the menu item Formativ adds to the main GroupWise menu. When running Formativ Admin or Formativ Developer, you can control the applet help hints and for library administrators, control whether the administrator library exception dialog is displayed on startup.

Paths

The paths tab contains the settings for the location of the various files listed below.

Personal Applets Directory

This is the directory where your personal applets will be stored. It can be located on your local hard disk or on a network drive.

Applet Data Directory

This is the directory where support files used by some applets is stored.

Library Backup Directory

Formativ Admin only. This is the directory into which the eDirectory library applets will be backed-up. This setting is useful only to library administrators (see the Administrators Guide for more information).

eDirectory

The eDirectory Configuration Discovery settings are used to control how your managed eDirectory/NDS configuration options are located. These settings should only ever be modified by a system administrator.

The Include NDS Groups in the configuration discovery process check box is used to control whether Formativ will examine your eDirectory group memberships to see if any of them contain Formativ Configuration information. See the Administrators Guide for more information.

The OU Search limit control is used to specify the maximum number of OU levels that Formativ will traverse when looking for configuration information. Limit this number if you need to avoid potential jumps across slow infrastructure, such as WAN links. See the Administrators Guide for more information.

Protocols

The Shared Applet Directory Access Protocols tab defines the mode in which Formativ should operate. The Use local applets only setting will force the client to operate in stand-alone workstation mode and it will only execute applets located in the Formativ personal applets directory.

Selecting The NetWare Client. If not available, use LDAP setting will enable the client to search for a Formativ Configuration object and Formativ Applet Libraries within eDirectory. If the NetWare Client is installed, the NDAP protocols will be used to access eDirectory and, if not, Formativ will attempt to access eDirectory via the LDAP protocol.

Selecting The following protocol options forces Formativ to either run using the NetWare Client or the LDAP protocol.

User Interface

The User Interface section lets you specify how many words of an applet name should appear on applet toolbar buttons within the GroupWise client. This is useful if you have configured GroupWise to display button text within toolbars. Since GroupWise makes all toolbar buttons the width of the widest button (based on the length of the text displayed on the button's caption) you should keep the number of words displayed to a minimum.

This section also contains options that let you control whether the special Formativ Portals folder is created in the GroupWise client. You can also specify the name of the portal folder, and optionally the name of an applet that should be executed when the portals folder is selected and no other portals exist.

LDAP

The LDAP page is divided into two areas - Server and User.

Server

Server Name - Enter the name of the LDAP server you wish to use. This can be in the form of an IP address, or the server name if you have access to a DNS server.

Server Port - Enter the port number of the LDAP server

Connect Using SSL - Check this box if you wish to connect to the LDAP server using SSL (Secure Sockets Layer)

SSL Certificate - Use the browse button to locate the SSL certificate you wish to use to connect to the LDAP server. You may specify a base 64 or DER certificate.

Cache all Subscribed Libraries - Check this box to have Formativ cache all subscribed applet libraries from the LDAP server.

User

Server Requires Me to Logon - Check this option if your LDAP server requires you to login.

User Name - Specify the DN of the username you wish to use to authenticate to the LDAP server.

<REQUIRES COMPLETION ONCE LDAP LOGIN OPERATION IS FINALIZED>

User